The idea behind ComboBox is to provide an easy way for users to choose an item from a list. 4th Dimension provides Choice Lists for this purpose, but the current implementation has several problems:
• The window containing the list of valid choices is physically separated from the layout’s enterable area. This causes a distraction as users must shift their focus from between two very different areas of the screen.
• The programmer has no control over the location of the choice list window or the appearance of the text in the window.
• Unless the list is sorted, users cannot simply type the entries they wish, even if they know what they are looking for.
• Even after a choice has been made, users can still modify the selected text to become something that is not in the list. This ability is not always desireable.
• The list of choices must reside in a 4D list, which is maintained on the server (in a multi-user environment). Any other user on the entire system can change this list even while it is in use.
ComboBox addresses these user-related problems while providing a programming interface that allows the area to adapt to practically any look and feel the designer wishes.
This package contains two copies of ComboBox. ComboBox.Lib uses the drag-and-drop, platform-independent extension architecture, and requires 4th Dimension 3.2.5 or greater or 4D Client and 4D Server 1.2.5 or greater. ComboBox.Ext can be installed using the 4D External Mover, and is for use with versions of 4th Dimension prior to 3.2.5. Both copies of ComboBox require System 7.0 or greater.
NOTE: It is extremely important that you do not include both copies of ComboBox for use with the same structure. You should either install ComboBox.Ext using the 4D External Mover, or install ComboBox.Lib by dragging it into the Mac4DX folder, but not both.
Source Code
For those who are interested, source code for the ComboBox external area is now available. Look for it in the archive from which you received this package. The ComboBox Source package includes all C source code files, resource files, and Metrowerks® CodeWarrior™ Gold 7 project files necessary to build the FAT version of the ComboBox external area. You will need to obtain the Platform- Independent Extension Authoring Kit from ACI or your local affiliate for the required header files.
This external area package is provided free of charge by Pensacola Christian College. You may use it in as many database applications as you desire. You may not sell it by itself or with any other group/bundle/collection of extensions, framework, shell, etc. It is provided free of charge, so don’t sell it for its own sake. Although you may distribute ComboBox freely, you may not charge any fee for the use, copying, or distribution of the product. Pensacola Christian College maintains ownership of the ComboBox external area package as well as this documentation.
If the text of this document, or any portion thereof, is duplicated and distributed by any means — physical, electronic, or otherwise — such duplication and distribution must include the text of this document in its entirety and unaltered. No fee may be charged for the for the duplication or distribution of the ComboBox external area or of this document.
By using or distributing ComboBox, you agree to this license and to the “No Warranty” section below.
No Warranty
PENSACOLA CHRISTIAN COLLEGE MAKES NO WARRANTY, EXPRESS OR IMPLIED, WITH RESPECT TO THIS SOFTWARE, ITS QUALITY, PERFORMANCE, OR FITNESS FOR A PARTICULAR PURPOSE. THIS SOFTWARE IS PROVIDED “AS IS,” AND YOU, THE CONSUMER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND PERFORMANCE.
IN NO EVENT WILL PENSACOLA CHRISTIAN COLLEGE AND/OR ANY OF ITS EMPLOYEES BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT IN THE SOFTWARE OR ITS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN PARTICULAR, NEITHER PENSACOLA CHRISTIAN COLLEGE NOR ANY OF ITS EMPLOYEES SHALL HAVE ANY LIABILITY FOR ANY HARDWARE, PROGRAMS OR DATA STORED IN OR USED WITH THIS PRODUCT, INCLUDING THE COSTS OF RECOVERING OR REPLACING SUCH HARDWARE, PROGRAMS OR DATA.
Acknowlegements
The behavior of the ComboBox external area package is based in part on the combo box from Microsoft® Windows™ and the AppleDirections articles “The Joys of Disambiguating,” March 1995, pp. 14-15, and “The Joys of Disambiguating, Part Two,” April 1995, pp. 14-16, by Peter Bickford.
Thanks to Dan Katz for providing the original ComboBox_DB database.
Thanks also to the members of the 4D list on the internet. To subscribe to the 4D list, send email to 4d-nug@liststar.fsti.com with the word “subscribe” in the subject of your message.
Most importantly, thanks to Jesus Christ for answering many “I’m stuck, Lord; please show me how to do this!” prayers, and for guiding me to the resources I needed to find the answers.
Comments
Send comments to Steve_Dwire@linq.pcci.edu.
About Pensacola Christian College
For more information about Pensacola Christian College and its related ministries, send e-mail to pccinfo@pcci.edu or visit our home page at http://www.pcci.edu.
Default Commands
CB_SetDefTxtFnt (FontNum; FontSize; FontStyle)
Sets the default font, size, and style for the text areas.
FontNum Integer: The number of the font to use for displaying the text. (Default = 1 {Geneva})
FontSize Integer: The size, in points, to use for displaying the text. (Default = 9)
FontStyle Integer: The sum of the following style attributes to use for displaying the text:
0 Plain
1 Bold
2 Italics
4 Underline
8 Outline
16 Shadow
32 Condensed
64 Extended
(Default = 0 {Plain})
CB_SetDefTxtCol (ForeColor; BackColor)
Sets the default colors for the text areas.
ForeColor Integer: The number (0-255) of the color from 4D’s palette to use for the text foreground. (Default = 15 {Black})
BackColor Integer: The number (0-255) of the color from 4D’s palette to use for the text background. (Default = 0 {White})
CB_SetDefLstFnt (FontNum; FontSize; FontStyle)
Sets the default font, size, and style for the lists.
FontNum Integer: The number of the font to use for displaying the lists. (Default = 1 {Geneva})
FontSize Integer: The size, in points, to use for displaying the lists. (Default = 9)
FontStyle Integer: The sum of the following style attributes to use for displaying the lists:
0 Plain
1 Bold
2 Italics
4 Underline
8 Outline
16 Shadow
32 Condensed
64 Extended
(Default = 0 {Plain})
CB_SetDefLstCol (ForeColor; BackColor)
Sets the default colors for the lists.
ForeColor Integer: The number (0-255) of the color from 4D’s palette to use for the list foreground. (Default = 15 {Black})
BackColor Integer: The number (0-255) of the color from 4D’s palette to use for the list background. (Default = 0 {White})
CB_SetDefLstRws (Rows)
Sets the default number of rows to display in the scrolling lists.
Rows Integer: The number of rows to display in the scrolling lists. (Default = 5)
Sets the default PICT resource IDs to use for the popup-indicator button. Set these values to zero (0) if you do not wish to have a popup-indicator button.
CUp Integer: PICT resource ID for the color picture of the popup-indicator button in the up (unpressed) position.
CDown Integer: PICT resource ID for the color picture of the popup-indicator button in the down (pressed) position.
CDisabled Integer: PICT resource ID for the color picture of the popup-indicator button when the area is disabled.
BUp Integer: PICT resource ID for the black & white picture of the popup-indicator button in the up (unpressed) position.
BDown Integer: PICT resource ID for the black & white picture of the popup-indicator button in the down (pressed) position.
BDisabled Integer: PICT resource ID for the black & white picture of the popup-indicator button when the area is disabled.
CB_SetDefGap (PICTGap; TopGap; LeftGap; RightGap)
Sets the default sizes (in pixels) of the gaps to leave in certain positions when drawing the area. ComboBox draws no boundaries of any kind around the popup-indicator button or the text area. You should draw your own boundaries behind the external area and set these gap values to allow those boundaries to show through the gaps. This strategy allows you to make ComboBox conform to your system’s own look and feel.
PICTGap Integer: The size of the gap between the popup-indicator button and the right edge of the text area. (Default = 0)
TopGap Integer: The size of the gap between the bottom of the external area and the top of the list window. (Default = 3)
LeftGap Integer: The size of the gap between the left edge of the external area and the left edge of the list window. (Default = 1)
Right Gap Integer: The size of the gap between the right edge of the external area and the right edge of the list window. (Default = 0)
CB_SetDefLead (Leading)
Sets the default distance (in pixels) between the top of the external area and the top of the text area.
Leading Integer: Distance between the top of the external area and the top of the text area. (Default = 1)
Sets the flags governing the default behavior of ComboBox areas.
CanFind Integer: When the user presses a key, if CanFind is one (1), ComboBox will select the first item the in the list that begins with what the user has typed. If CanFind is zero (0), ComboBox will not change the selection in the list. (Default = 1)
CanFill Integer: When the user presses a key and ComboBox finds an item in the list that begins with what the user has typed, if CanFill is one (1), ComboBox will fill in the text area with the item from the list. If CanFill is zero(0), ComboBox will not change the text area. (Default = 1)
CanList Integer: If CanList is one (1), ComboBox will display the list of choices when the user clicks on the popup-indicator button. Clicking on the popup-indicator button when the list is open will close the list. If CanList is zero (0), the list of choices will not be displayed. (Default = 1)
CanEdit Integer: If CanEdit is one (1), ComboBox will allow the user to edit the text in the text area. ComboBox’s searching is based on the text found in the text area, and searching occurs only when the insertion point is at the end of the text. Use this option if the user can choose items that are not in the list. If CanEdit is zero (0), the user cannot edit or change the selection of the text in the text area. ComboBox’s searching is based on the characters the user has typed. The search string is reset whenever there is a pause in typing longer than the double-click time set in the Mouse Control Panel. (Default = 0)
ListOnActivate Integer: If ListOnActivate is one (1), the list of choices will appear whenever the external area is activated. If ListOnActivate is zero (0), it will not. Setting ListOnActivate to one (1) overrides CanList, and forces it to one (1). (Default = 1)
ListOnKey Integer: If ListOnKey is one (1), the list of choices will appear whenever the user types into the text area (see CanFind). If ListOnKey is zero (0), it will not. Setting ListOnKey to one (1) overrides CanList, and forces it to one (1). (Default = 1)
Area Commands
CB_SetTxtFnt (Area; FontNum; FontSize; FontStyle)
Sets the font, size, and style for a text area.
Area LongInt: The area to change.
FontNum Integer: The number of the font to use for displaying the text.
FontSize Integer: The size, in points, to use for displaying the text.
FontStyle Integer: The sum of the following style attributes to use for displaying the text:
0 Plain
1 Bold
2 Italics
4 Underline
8 Outline
16 Shadow
32 Condensed
64 Extended
CB_SetTxtCol (Area; ForeColor; BackColor)
Sets the colors for a text area.
Area LongInt: The area to change.
ForeColor Integer: The number (0-255) of the color from 4D’s palette to use for the text foreground.
BackColor Integer: The number (0-255) of the color from 4D’s palette to use for the text background.
CB_SetLstFnt (Area; FontNum; FontSize; FontStyle)
Sets the font, size, and style for a list.
Area LongInt: The area to change.
FontNum Integer: The number of the font to use for displaying the list.
FontSize Integer: The size, in points, to use for displaying the list.
FontStyle Integer: The sum of the following style attributes to use for displaying the list:
0 Plain
1 Bold
2 Italics
4 Underline
8 Outline
16 Shadow
32 Condensed
64 Extended
CB_SetLstCol (Area; ForeColor; BackColor)
Sets the colors for a list.
Area LongInt: The area to change.
ForeColor Integer: The number (0-255) of the color from 4D’s palette to use for the list foreground.
BackColor Integer: The number (0-255) of the color from 4D’s palette to use for the list background.
CB_SetLstRws (Area; Rows)
Sets the number of rows to display in the scrolling list.
Area LongInt: The area to change.
Rows Integer: The number of rows to display in the scrolling list.
Sets the sizes (in pixels) of the gaps to leave in certain positions when drawing the area. ComboBox draws no boundaries of any kind around the popup-indicator button or the text area. You should draw your own boundaries behind the external area and set these gap values to allow those boundaries to show through the gaps. This strategy allows you to make ComboBox conform to your system’s own look and feel.
Area LongInt: The area to change.
PICTGap Integer: The size of the gap between the popup-indicator button and the right edge of the text area.
TopGap Integer: The size of the gap between the bottom of the external area and the top of the list window.
LeftGap Integer: The size of the gap between the left edge of the external area and the left edge of the list window.
Right Gap Integer: The size of the gap between the right edge of the external area and the right edge of the list window.
CB_SetLead (Area; Leading)
Sets the distance (in pixels) between the top of the external area and the top of the text area.
Area LongInt: The area to change.
Leading Integer: Distance between the top of the external area and the top of the text area. (Default = 1)
Sets the flags governing the behavior of a ComboBox area.
Area LongInt: The area to change.
CanFind Integer: When the user presses a key, if CanFind is one (1), ComboBox will select the first item the in the list that begins with what the user has typed. If CanFind is zero (0), ComboBox will not change the selection in the list.
CanFill Integer: When the user presses a key and ComboBox finds an item in the list that begins with what the user has typed, if CanFill is one (1), ComboBox will fill in the text area with the item from the list. If CanFill is zero(0), ComboBox will not change the text area.
CanList Integer: If CanList is one (1), ComboBox will display the list of choices when the user clicks on the popup-indicator button. Clicking on the popup-indicator button when the list is open will close the list. If CanList is zero (0), the list of choices will not be displayed.
CanEdit Integer: If CanEdit is one (1), ComboBox will allow the user to edit the text in the text area. ComboBox’s searching is based on the text found in the text area, and searching occurs only when the insertion point is at the end of the text. Use this option if the user can choose items that are not in the list. If CanEdit is zero (0), the user cannot edit or change the selection of the text in the text area. ComboBox’s searching is based on the characters the user has typed. The search string is reset whenever there is a pause in typing longer than the double-click time set in the Mouse Control Panel.
ListOnActivate Integer: If ListOnActivate is one (1), the list of choices will appear whenever the external area is activated. If ListOnActivate is zero (0), it will not. Setting ListOnActivate to one (1) overrides CanList, and forces it to one (1).
ListOnKey Integer: If ListOnKey is one (1), the list of choices will appear whenever the user types into the text area (see CanFind). If ListOnKey is zero (0), it will not. Setting ListOnKey to one (1) overrides CanList, and forces it to one (1).
CB_FillLst (Area; “ArrayName”)
Fills the selected area’s list with the elements of a text array.
Area LongInt: The area to change.
ArrayName String: The name of the text array that holds the elements that belong in the area’s list. The array must be either a process array or an interprocess array. No local arrays are allowed.
CB_UpdateLst (Area)
Updates the list’s internal data to reflect any changes in the array specified with CB_FillLst. Call CB_UpdateLst whenever you make a change to your array.
Area LongInt: The area to change.
CB_SetLstPos (Area; Position)
Selects a particular item in an area’s list. CB_SetLstPos also changes the text of the text area to reflect the item selected in the list.
Area LongInt: The area to change.
Position Integer: The element number to select in the list.
CB_SetTxt (Area; Text)
Sets the text of the text area. If you wish to set the text area to reflect a certain element of the list, use CB_SetLstPos.
Area LongInt: The area to change.
Text Text: The text to display in the text area.
CB_SetModified (Area; Modified)
Sets or un-sets the modified flag for a particular area. The modified flag is usually set whenever the user makes a change to the text in the area.
Area LongInt: The area to change.
Modified Integer: One (1) to set the modified flag or zero (0) to un-set it.
CB_SetEnabled (Area; Enable)
Enables or disables a particular area. Because of an apparent limitation in 4th Dimension’s extension interface, a user can click on or tab into a ComboBox area even when it is disabled. When this happens, the area receives the input focus, but nothing happens. When an area is disabled, the popup-indicator button changes to the disabled PICT resource. It is the responsibility of the designer to change the color of the text, if desired, using CB_SetTxtCol.
Area LongInt: The area to change.
Enable Integer: One (1) to set enable the area or zero (0) to disable it.
CB_SetHilite (Area; Start; End)
Sets the hilight range of the ComboBox’s text area. This command should not normally be used on an area whose CanEdit flag (see CB_SetFlags) is set to zero (0).
Area LongInt: The area to change.
Start Integer: Number of the character after which the highlighting should start. Zero (0) to start at the beginning.
End Integer: Number of the character after which the highlighting should end.
To move the insertion point, call CB_SetHilite with Start and End both equal to the number of the character after which the insertion point should be located.
Information Commands
CB_GetLstRws (Area) -> LongInt
Gets the number of rows an area is set to display in the scrolling list.
Area LongInt: The area to check.
Returns the number of rows the area is set to display in the scrolling list.
CB_GetLstPos (Area) -> LongInt
Gets the element number currently selected in an area’s scrolling list.
Area LongInt: The area to check.
Returns the element number currently selected in the list. Note that when the CanEdit flag is set to one (1) (see CB_SetFlags), the text of the selected element is not necessarily the same as the text in the text area even if there is an element in the list with text that matches the text area. This is true because when the CanEdit flag is set to one (1), ComboBox searches only when the insertion point is at the end of the text.
CB_GetTxt (Area; Text)
Gets the text from the text area.
Area LongInt: The area to check.
Text Text: A text variable to accept the text from the text area.
CB_GetModified (Area) -> LongInt
Determines whether or not the area has been modified since it was selected.
Area LongInt: The area to check.
Returns one (1) if the area has been modified since it was selected. Otherwise, returns zero (0).
CB_GetEnabled (Area) -> LongInt
Determines whether or not the area is enabled.
Area LongInt: The area to check.
Returns one (1) if the area is enabled. Otherwise, returns zero (0).
CB_GetHilite (Area; Start; End)
Gets the hilight range of the ComboBox’s text area.
Area LongInt: The area to check.
Start Integer: Integer variable to receive the number of the character after which the highlighting starts.
End Integer: Integer variable to receive the number of the character after which the highlighting ends.
CB_GetFontNum (“FontName”) -> LongInt
Returns the Font Number of the specified font.
FontName String: The name of the desired font.
Returns the font number of the font specified in FontName.
Update History
1.1.1 Kept ComboBox areas from “swallowing” the escape key. This change was necessary to allow the Customizer settings to work properly when the escape key is assigned to the “Cancel Layout” function.
Fixed a crashing bug revealed with Charlie Rieman’s “Less-Obnoxious Bus Error” control panel.
Fixed a bug that caused some of a layout’s text fields to display improperly in the design environment.
Compiled with better optimizations, reducing the size of the FAT version by about 1K.
1.1 (release) Added CB_GetFontNum function.
ComboBox now draws its default appearance in the design environment.
Fixed crashing problem with CB_SetDefGap.
Included Demo database from Dan Katz.
Included Proc.ext-compatible version. WARNING: Do not include both the ComboBox.Lib and the ComboBox.Ext versions in the same database.
1.1 a2 Made PPC version into a Disk Fragment so it works with 4D x.5.
1.1 a1 Kept ComboBox areas from “swallowing” the Enter key.
Fixed a problem of “dead” scroll bars with multiple ComboBoxes on one layout.
Made closing the list window call the ComboBox object’s script.
1.0.2 (Maintenance Release) Made PPC version into a Disk Fragment so it works with 4D x.5.
1.0.1 Fixed a problem that caused the list box to remain empty on the screen. Even though typing would choose one of the items, the items never displayed. This would happen only on occasion, but when it did, it happened for the entire session on that database.
Fixed a problem where clicking on a non-selectable object (a button, for example) would clear a ComboBox’s Modified flag.
1.0 Initial Release
Known Problems and Limitations
1) Disabled areas still receive input focus. This appears to be a limitation of 4D's extension architecture.
2) When a ComboBox area is used in a modal (type 1) window and the user opens the list, 4D captures any mouse click in the list and beeps rather than allowing a list item to be chosen. Note that this happens only when the area is in a modal window.
3) The Color popup-indicator PICT resources are used even when the monitor is set to black & white.
4) String comparisons are always diacritical-sensitive and limited to ASCII text. There are currently no plans to support multi-lingual character sets in the near future.
If anyone finds other problems or knows how to work around these problems, please let me know at Steve_Dwire@linq.pcci.edu.
Thanks,
Steve Dwire
(CodeWarrior is a trademark and Metrowerks is a registered trademark of Metrowerks, Inc. 4D is a trademark and 4th Dimension is a registered trademark of ACI/ACI US. All other trademarks or registered trademarks are property of their respective owners.)
